Skip to main content
Version: 1.1.0

Search API

Search service API Documentation

Paths

/cl/search/api/v1/healthz/

  • Method: GET
  • Summary: Health
  • Description: Return Health Status. :return:
  • Operation ID: health_cl_search_api_v1_healthz__get
  • Responses:
    • 200:
      • Description: Successful Response
      • Content-Type: application/json

Semantic Search API

/cl/search/api/v1/semantic

  • Method: POST

  • Summary: Semantic Search On Tenant Data

  • Description: Perform a semantic search on tenant data present in the object repository and return a list of matching documents.

  • Operation ID: Semantic_search_on_tenant_data_present_cl_search_api_v1_semantic_post

Request Payload:

TypeParameterDescriptionData Typeis_optional
Query Parameterquery_stringQuery string to search for objects semanticallystringmandatory
Query ParameterstartSpecifies the page number to retrieve (1-based index)intmandatory
Query ParametersizeSpecifies the number of items per pageintmandatory
Query Parametermin_relevant_scoreMinimum relevant scoreintmandatory
ParametertagsList of tags associated with the documentarray of stringsmandatory
ParameterfoldersList of folders where the document is organizedarray of stringsmandatory
ParameterreposList of repositories where the document is storedarray of stringsmandatory
ParameterkvpKey-value pairs for additional metadataobjectmandatory
ParametertaxonomyTaxonomy information related to the documentarray of objectsmandatory

sample code

import requests
URL = "https://api.kadal.ai/cl/search/api/v1/semantic"

# sample python code
headers = { "Authorization ": "Bearer 1234567890" }
params={
"query_string":"string",
"start":"int",
"size":"int",
"min_relevant_score":"int",
"tags": [
"string"
],
"folders": [
"string"
],
"repos": [
"string"
],
"kvp": {},
"taxonomy": {}
}

response = requests.post(URL, headers=headers,params=params)
print(response)

Example response -

{
"status": "200",
"message": "Documents found",
"result_count": 0,
"result": [],
"aggregation": {}
}

Responses:

Status CodeDescriptionContent-Type
200Documents foundapplication/json
400Bad Requestapplication/json
401Unauthorizedapplication/json
403Forbiddenapplication/json
404Object not foundapplication/json
405Method not allowedapplication/json
422Unprocessable Entityapplication/json
500Internal server errorapplication/json
  • 200 (Documents found): This response indicates that the semantic search operation was successful, and it returns a list of matching documents.
  • 400 (Bad Request): This response indicates that the request was malformed or invalid.
  • 401 (Unauthorized): This response indicates that the request lacks valid authentication credentials for the operation.
  • 403 (Forbidden): This response indicates that the request is forbidden due to insufficient permissions.
  • 404 (Object not found): This response indicates that the requested object or resource was not found.
  • 405 (Method not allowed): This response indicates that the HTTP method used is not allowed for this endpoint.
  • 422 (Unprocessable Entity): This response indicates that the request was well-formed but unable to be followed due to semantic errors.
  • 500 (Internal server error): This response indicates an unexpected server error occurred.

Note: Use this API to perform a semantic search on tenant data present in the object repository. Ensure that the request parameters are correctly formatted and that authentication credentials are provided as required.

Full-Text Search API

/cl/search/api/v1/fulltext

  • Method: POST

  • Summary: Full-Text Search On Tenant Data

  • Description: Perform a full-text search on tenant data present in the object repository and return a list of matching documents.

  • Operation ID: Full_text_search_on_tenant_data_present_cl_search_api_v1_fulltext_post

Request Payload:

TypeParameterDescriptionData Typeis_optional
Query Parameterquery_stringQuery string to search for objects semanticallystringmandatory
Query ParameterstartSpecifies the page number to retrieve (1-based index)stringmandatory
Query ParametersizeSpecifies the number of items per pageintmandatory
Query Parametermin_relevant_scoreMinimum relevant scoreintmandatory
ParametertagsList of tags associated with the documentlistmandatory
ParameterfoldersList of folders where the document is organizedlistmandatory
ParameterreposList of repositories where the document is storedlistmandatory
ParameterkvpKey-value pairs for additional metadatalistmandatory
ParametertaxonomyTaxonomy information related to the documentlistmandatory

sample code

import requests
URL = "https://api.kadal.ai/cl/search/api/v1/fulltext"

# sample python code
headers = { "Authorization ": "Bearer 1234567890" }

params={
"query_string":"string",
"start":"int",
"size":"int",
"min_relevant_score":"int",
"tags": [
"string"
],
"folders": [
"string"
],
"repos": [
"string"
],
"kvp": "list",
"taxonomy": "list",
}

response = requests.post(URL, headers=headers,params=params)
print(response)

Example response -

{
"status": "200",
"message": "Documents found",
"result_count": 0,
"result": [],
"aggregation": {}
}

Responses:

Status CodeDescriptionContent-Type
200Documents foundapplication/json
400Bad Requestapplication/json
401Unauthorizedapplication/json
403Forbiddenapplication/json
404Object not foundapplication/json
405Method not allowedapplication/json
422Unprocessable Entityapplication/json
500Internal server errorapplication/json
  • 200 (Documents found): This response indicates that the full-text search operation was successful, and it returns a list of matching documents.
  • 400 (Bad Request): This response indicates that the request was malformed or invalid.
  • 401 (Unauthorized): This response indicates that the request lacks valid authentication credentials for the operation.
  • 403 (Forbidden): This response indicates that the request is forbidden due to insufficient permissions.
  • 404 (Object not found): This response indicates that the requested object or resource was not found.
  • 405 (Method not allowed): This response indicates that the HTTP method used is not allowed for this endpoint.
  • 422 (Unprocessable Entity): This response indicates that the request was well-formed but unable to be followed due to semantic errors.
  • 500 (Internal server error): This response indicates an unexpected server error occurred.

Note: Use this API to perform a full-text search on tenant data present in the object repository. Ensure that the request parameters are correctly formatted and that authentication credentials are provided as required.

Basic Search API

  • Method: POST

  • Summary: Basic Search On Tenant Data

  • Description: Perform a basic search on tenant data present in the object repository and return a list of matching documents based on a specified query.

  • Operation ID: Basic_search_on_tenant_data_present_cl_search_api_v1_basic_search_post

Request Payload:

Query ParameterParameterDescriptionData Typeis_optional
query_stringprovide string queryobject (dictionary)Yes
kvpKey-value pairs for additional metadatadictionaryYes
tagsList of tags associated with the requeststringsYes
reposList of repositories linked to the requeststringsYes
foldersList of folders associated with the requeststringsYes
created_betweenFilter results by creation date rangelistYes
modified_betweenFilter results by modification date rangelistYes
deleted_betweenFilter results by deletion date rangelistYes
startIndex of the first item to retrieve in the result setintegerNo
sizeNumber of items to retrieve per pageintegerNo

sample code

import requests
URL = "https://api.kadal.ai/cl/search/api/v1/basic_search"

# sample python code
headers = { "Authorization ": "Bearer 1234567890" }

params={
"query_dictionary": {
"kvp": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"tags": [
"string"
],
"repos": [
"string"
],
"folders": [
"string"
],
"start": "int",
"size": "int",
"source": "string",
"created_between": "list",
"modified_between": "list",
"deleted_between":"list",
}
}



response = requests.post(URL, headers=headers,params=params)
print(response)

Example response -

{
"status": "200",
"message": "Documents found",
"result_count": 0,
"result": [],
"aggregation": {}
}

Responses:

Status CodeDescriptionContent-Type
200Documents foundapplication/json
400Bad Requestapplication/json
401Unauthorizedapplication/json
403Forbiddenapplication/json
404Object not foundapplication/json
405Method not allowedapplication/json
422Unprocessable Entityapplication/json
500Internal server errorapplication/json
  • 200 (Documents found): This response indicates that the basic search operation was successful, and it returns a list of matching documents based on the query.
  • 400 (Bad Request): This response indicates that the request was malformed or invalid.
  • 401 (Unauthorized): This response indicates that the request lacks valid authentication credentials for the operation.
  • 403 (Forbidden): This response indicates that the request is forbidden due to insufficient permissions.
  • 404 (Object not found): This response indicates that the requested object or resource was not found.
  • 405 (Method not allowed): This response indicates that the HTTP method used is not allowed for this endpoint.
  • 422 (Unprocessable Entity): This response indicates that the request was well-formed but unable to be followed due to semantic errors.
  • 500 (Internal server error): This response indicates an unexpected server error occurred.

Note: Use this API to perform a basic search on tenant data present in the object repository using a specified query. Ensure that the request parameters are correctly formatted and that authentication credentials are provided as required.

Search APIs

/cl/search/api/v1/search

  • Method: POST

  • Summary: Search With Reranking

  • Description: Re-rank search results obtained through semantic and full-text search.

  • Operation ID: search_with_reranking_cl_search_api_v1_search_post

Request Payload:

TypeParameterDescriptionData Typeis_optional
Query Parameterquery_stringQuery string to searchstringmandatory
Query Parametertop_kDefault value for top_k (Default: 5)intmandatory
Query Parameterre_rankedRe-rank the search resultsbooleanmandatory
ParametertagsList of tags associated with the documentlistmandatory
ParameterfoldersList of folders where the document is organizedlistmandatory
ParameterreposList of repositories where the document is storedlistmandatory
ParameterkvpKey-value pairs for additional metadatalistmandatory
ParametertaxonomyTaxonomy information related to the documentlistmandatory

sample code

import requests
URL = "https://api.kadal.ai/cl/search/api/v1/search"

# sample python code
headers = { "Authorization ": "Bearer 1234567890" }

params={
"query_string":"string",
"top_k":"int",
"re_ranked":"bool",
"tags": [
"string"
],
"object_ids": [
"string"
],
"folders": [
"string"
],
"repos": [
"string"
],
"kvp": "list",
"taxonomy": "list",

}


response = requests.post(URL, headers=headers,params=params)
print(response)

Example response -

{
"status": "string",
"message": "string",
"data": "string"
}

Responses:

Status CodeDescriptionContent-Type
200Successful Responseapplication/json
422Validation Errorapplication/json
  • 200 (Successful Response): This response indicates that the search with reranking operation was successful.
  • 422 (Validation Error): This response indicates that there was a validation error with the request.

/cl/search/api/v1/search_lite

  • Method: GET

  • Summary: Search With Reranking

  • Description: Search the database for similar documents using k-nn search provided by OpenSearch.

  • Operation ID: search_with_reranking_cl_search_api_v1_search_lite_get

Request Payload:

TypeParameterDescriptionData Typeis_optional
Parameterquery_stringQuery string to searchstringmandatory
Parametertop_kDefault value for top_k (Default: 5)intmandatory
Parameterre_rankedRe-rank the search results for similar documentsbooleanmandatory

sample code

import requests
URL = "https://api.kadal.ai/cl/search/api/v1/search_lite"

# sample python code
headers = { "Authorization ": "Bearer 1234567890" }

params={
"query_string":"string",
"top_k":"int",
"re_ranked":"bool"
}
response = requests.get(URL, headers=headers,params=params)
print(response)

Example response -

{
"status": "string",
"message": "string",
"data": "string"
}

Responses:

Status CodeDescriptionContent-Type
200Successful Responseapplication/json
422Validation Errorapplication/json
  • 200 (Successful Response): This response indicates that the search with reranking operation was successful.
  • 422 (Validation Error): This response indicates that there was a validation error with the request.

Note:

  • Use /cl/search/api/v1/search to perform a search with reranking on search results obtained through semantic and full-text search.
  • Use /cl/search/api/v1/search_lite to perform a search for similar documents using k-nn search provided by OpenSearch. Ensure that the request parameters are correctly formatted and that authentication credentials are provided as required.

Components

Schemas

BasicSearchRequest

  • Type: object
  • Description:
  • Properties:
    • kvp:
      • Type: object
    • tags:
      • Type: array
    • repos:
      • Type: array
    • folders:
      • Type: array
    • created_between:
      • Type: array
    • modified_between:
      • Type: array
    • deleted_between:
      • Type: array
    • start:
      • Type: integer
    • size:
      • Type: integer

Body_Full_text_search_on_tenant_data_present_cl_search_api_v1_fulltext_post

  • Type: object
  • Description:
  • Properties:
    • tags:
      • Type: array
    • folders:
      • Type: array
    • repos:
      • Type: array
    • kvp:
      • Type: object
    • taxonomy:
      • Type: object

Body_Semantic_search_on_tenant_data_present_cl_search_api_v1_semantic_post

  • Type: object
  • Description:
  • Properties:
    • tags:
      • Type: array
    • folders:
      • Type: array
    • repos:
      • Type: array
    • kvp:
      • Type: object
    • taxonomy:
      • Type: object

Body_search_with_reranking_cl_search_api_v1_search_post

  • Type: object
  • Description:
  • Properties:
    • tags:
      • Type: array
    • object_ids:
      • Type: array
    • folders:
      • Type: array
    • repos:
      • Type: array
    • kvp:
      • Type: object
    • taxonomy:
      • Type: object

HTTPValidationError

  • Type: object
  • Description:
  • Properties:
    • detail:
      • Type: array

Msg

  • Type: object
  • Description:
  • Properties:
    • msg:
      • Type: string

QueryResponse

  • Type: object
  • Description:
  • Properties:
    • status:
      • Type: string
    • message:
      • Type: string
    • result_count:
      • Type: integer
    • result:
    • aggregations:

ValidationError

  • Type: object
  • Description:
  • Properties:
    • loc:
      • Type: array
    • msg:
      • Type: string
    • type:
      • Type: string

Search Service API Documentation

Version: 2.0.0

Overview

This API provides comprehensive search capabilities for content stored in LOR-NG. It supports various search types including basic search, semantic search, fulltext search, and re-ranked search operations.

Authentication

The API uses OAuth 2.0 with Bearer token authentication. Include the following header in all requests:

Authorization: Bearer <your_token>

API Versions

The API is available in multiple versions with different capabilities:

API v1

  • Basic health check endpoint
  • Legacy search endpoints

API v2

  • Basic Search
  • Fulltext Search
  • Semantic Search
  • Re-ranked Search
  • Chunk Search

API v3

  • Classify and Re-ranked Search
  • Enhanced Basic Search with folder support

Endpoints

Health Check

GET /cl/search/api/v1/healthz/

Returns the health status of the service.

Response:

  • 200: Successful Response (application/json)

Search Endpoints

POST /cl/search/api/v2/semantic

Description: Perform a semantic search on tenant data present in the object repository.

Request Payload:

TypeParameterDescriptionRequired
Query Parameterquery_stringQuery string to search for objectsYes
Query Parametersorting_bySorting by (Available values: None, title, updated_at)No
Query ParameterorderSort result in ascending or descending order (Available values: None, asc, desc)No
Query Parameterpage_noDefault value: 1No
Query Parameterpage_sizeDefault value: 20No
Query Parametermin_relevant_scoreDefault value: 0.5No
Parameterobject_idsList of object IDsYes
ParameterfoldersList of foldersYes
Parameterobject_typeList of object typesYes
Parameterfile_extensionList of file extensionsYes
ParametertitleTitle of the objectYes
ParametersizeSize of the objectYes
Parameterfile_nameList of file namesYes
ParameterreposList of repositoriesYes
Parameterext_user_id_refExternal user ID referenceYes
Parametersystem_metadataMetadata for system (created_by, updated_by, etc.)Yes
Parametercustom_metadataCustom metadata (tags, kvp, taxonomy)Yes
Parametermedia_metadataMetadata related to mediaYes
Parametersource_system_metadataSource system metadata (source_system_id, source_url, etc.)Yes

Request Payload Structure:

{
"query_string": "<string>",
"start": "<integer>",
"size": "<integer>",
"min_relevant_score": "<integer>",
"tags": ["<string>"],
"folders": ["<string>"],
"repos": ["<string>"],
"kvp": {
"key1": "value1",
"key2": "value2"
},
"taxonomy": {
"taxonomy_key1": "taxonomy_value1",
"taxonomy_key2": "taxonomy_value2"
}
}

Sample Code:

import requests
URL = "https://api.kadal.ai/cl/search/api/v2/semantic"

headers = {"Authorization": "Bearer 1234567890"}
params = {
"query_string": "string",
"start": 1,
"size": 10,
"min_relevant_score": 0,
"tags": ["string"],
"folders": ["string"],
"repos": ["string"],
"kvp": {},
"taxonomy": {}
}

response = requests.post(URL, headers=headers, json=params)
POST /cl/search/api/v2/fulltext

Description: Perform a full-text search with relevance scoring.

Request Payload:

TypeParameterData TypeDescriptionRequired
Query Parameterquery_stringstringQuery string to search for objectsYes
Query Parametersorting_bystringSorting criteria (Available values: None, title, updated_at; Default: None)No
Query ParameterorderstringSort order (Available values: None, asc, desc; Default: asc)No
Query Parameterpage_nointegerPage number (Default: 1)No
Query Parameterpage_sizeintegerItems per page (Default: 20)No
Query Parametermin_relevant_scorenumberMinimum relevance score (Default: 0.5)No
Parameterobject_idsarrayList of object IDsNo
ParameterfoldersarrayList of foldersNo
Parameterobject_typearrayList of object typesNo
Parameterfile_extensionarrayList of file extensionsNo
ParametertitlestringTitle filterNo
ParametersizeintegerSize filterNo
Parameterfile_namearrayList of file namesNo
ParameterreposarrayList of repositoriesNo
Parameterext_user_id_refstringExternal user ID referenceNo
Parametersystem_metadataobjectSystem metadata including created_by, updated_by, is_deleted, license info, timestamps, etc.No
Parametercustom_metadataobjectCustom metadata (tags, kvp, taxonomy)No
Parametermedia_metadataobjectMedia-specific metadataNo
Parametersource_system_metadataobjectSource system metadata (source_system_id, connector_info, source_url)No
POST /cl/search/api/v2/basic_search

Description: Basic search functionality with advanced filtering options.

Request Payload:

TypeParameterTypeDescriptionRequired
Query Parameterquery_stringstringQuery string to search for objectsYes
Query Parametersorting_bystringSorting by (Available values: None, Default: None)No
Query ParameterorderstringSort result in ascending or descending order (Default: asc)No
Query Parameterpage_nointegerPage number (Minimum: 1, Default: 1)No
Query Parameterpage_sizeintegerPage size (Default: 20)No
Parameterobject_idsarrayList of object IDsNo
ParameterfoldersarrayList of foldersNo
Parameterobject_typearrayList of object typesNo
Parameterfile_extensionarrayList of file extensionsNo
ParametertitlestringTitle filterNo
ParametersizeintegerSize filterNo
Parameterfile_namearrayList of file namesNo
ParameterreposarrayList of repositoriesNo
Parameterext_user_id_refstringExternal user ID referenceNo
Parametersystem_metadataobjectSystem metadata including created_by, updated_by, etc.No
Parametercustom_metadataobjectCustom metadata (tags, kvp, taxonomy)No
Parametermedia_metadataobjectMedia-specific metadataNo
Parametersource_system_metadataobjectSource system metadata (source_system_id, connector_info, source_url)No
Parameterwith_exact_searchbooleanPerform exact match searchNo
Parameterwith_highlightbooleanHighlight matching termsNo
Parameteris_anywherebooleanPerform anywhere searchNo
POST /cl/search/api/v2/search

Description: Re-ranks search results from semantic and full-text search.

Request Payload:

TypeParameterDescriptionRequired
Query Parameterquery_stringSearch queryYes
Query Parameterre_rankedEnable re-ranking (Default value: true)Yes
Query Parameterpage_noPage number (Default value: 1, minimum: 1)No
Query Parameterpage_sizePage size (Default value: 20, minimum: 20)No
Parameterobject_idsList of object IDsYes
ParameterfoldersList of foldersYes
Parameterobject_typeList of object typesYes
Parameterfile_extensionList of file extensionsYes
ParametertitleTitle of the objectYes
ParametersizeSize of the objectYes
Parameterfile_nameList of file namesYes
ParameterreposList of repositoriesYes
Parameterext_user_id_refExternal user ID referenceYes
Parametersystem_metadataMetadata for system (created_by, updated_by, etc.)Yes
Parametercustom_metadataCustom metadata (tags, kvp, taxonomy)Yes
Parametermedia_metadataMetadata related to mediaYes
Parametersource_system_metadataSource system metadata (source_system_id, source_url, etc.)Yes

Common Response Format

{
"status": "200",
"message": "Documents found",
"result_count": 0,
"result": [],
"aggregation": {}
}
POST /cl/search/api/v2/chunk/search

Description: Enables re-ranking of search results based on semantic and full-text search relevance.

Request Payload:

TypeParameterDescriptionRequired
Query Parameterquery_stringQuery string for semantic searchYes
Query Parameterpage_sizeItems per page (Default value: 5)No
Query Parameterpage_noPage number (Default value: 1)No
Parameterobject_idsList of object IDsYes
Parametercustom_metadataCustom metadata (tags, kvp, taxonomy)Yes

Common Response Format

{
"status": "200",
"message": "Request successful",
"result_count": 0,
"result": [],
"aggregation": {},
"error": null
}

Response Status Codes

CodeDescription
200Documents found
400Bad Request
401Unauthorized
403Forbidden
404Object not found
405Method not allowed
422Unprocessable Entity
500Internal server error

Search Features

Basic Features

  • Exact match searching
  • Highlight support
  • Anywhere search
  • Combined objects search
  • Folder-only search

Advanced Features

  • Semantic search capabilities
  • Full-text search with relevance scoring
  • Re-ranking of search results
  • Query classification
  • Chunk-based search

Pagination

All search endpoints support pagination with:

  • page_no: Page number (starts from 1)
  • page_size: Number of results per page

Common Request Parameters

Search Filters

  • object_ids: Filter by specific object IDs
  • folders: Filter by folders
  • object_type: Filter by content types (Document, Audio, Video, etc.)
  • file_extension: Filter by file types (pdf, docx, mp4, etc.)
  • title: Filter by title
  • size: Filter by size
  • file_name: Filter by file names
  • repos: Filter by repositories

Metadata Filters

  1. System Metadata

    • created_by
    • updated_by
    • is_private
    • is_deleted
    • license information
    • timestamps
  2. Custom Metadata

    • tags
    • key-value pairs (kvp)
    • taxonomy
  3. Media Metadata

    • Custom media-specific properties
  4. Source System Metadata

    • source_system_id
    • connector_info
    • source_url